import Example from '~/components/example'
import { Code, InlineCode } from '~/components/text/code'
import Link from '~/components/text/link'
import {
  InputTable,
  OutputTable,
  Row,
  Cell,
  TypeCell,
  BoldCell,
  BooleanCell
} from '~/components/api/table'
import Endpoint from '~/components/api/endpoint'
import Request from '~/components/api/request'

export const meta = {
  editUrl: 'pages/docs/api/v1/api-docs-mdx/endpoints/aliases.mdx',
  lastEdited: '2019-09-09T08:52:07.000Z'
}

## Aliases

### List all the aliases

<Endpoint method="GET" url="/v2/now/aliases" />

Retrieves all of the active aliases for the authenticated account.

#### Request Query Parameters

The response of this API can be controlled with the following optional query parameters.

| Key           | Description                                          |
| ------------- | ---------------------------------------------------- |
| **limit**     | Maximum number of aliases to list from a request.    |
| **from**      | Get aliases created after this JavaScript timestamp. |
| **projectId** | Filter aliases from the given `projectId`.           |

The body will contain an entry for each alias.

#### Output

<OutputTable>
  <Row>
    <BoldCell>uid</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The unique identifier of the alias.</Cell>
  </Row>
  <Row>
    <BoldCell>alias</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>
      The alias name, it could be a <InlineCode>.now.sh</InlineCode> subdomain
      or a custom domain.
    </Cell>
  </Row>
  <Row>
    <BoldCell>created</BoldCell>
    <TypeCell>Date</TypeCell>
    <Cell>The date when the alias was created.</Cell>
  </Row>
  <Row>
    <BoldCell>deployment</BoldCell>
    <TypeCell>Map</TypeCell>
    <Cell>A map with the deployment ID and url.</Cell>
  </Row>
  <Row>
    <BoldCell>deploymentId</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The deployment ID.</Cell>
  </Row>
  <Row>
    <BoldCell>rules</BoldCell>
    <TypeCell>List</TypeCell>
    <Cell>
      The configured rules for{' '}
      <Link href="/docs/features/path-aliases">path alias</Link>.
    </Cell>
  </Row>
</OutputTable>

#### Deployment

This is the format of the `deployment` described above.

<OutputTable>
  <Row>
    <BoldCell>id</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The deployment unique identifier.</Cell>
  </Row>
  <Row>
    <BoldCell>url</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>The deployment unique URL.</Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  url="https://api.zeit.co/v2/now/aliases"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`
  }}
/>

Example successful (**200**) response:

<Code lang="json">{`{
    "aliases": [
      {
        "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
        "alias": "my-alias",
        "created": "2016-06-02T21:01:40.950Z",
        "deployment": {
          "id": "c9MrOWGzdJSfPxqyTDYhdEGN",
          "url": "my-app-fjvngszyiq.now.sh"
        },
        "deploymentId": "c9MrOWGzdJSfPxqyTDYhdEGN"
      },
      {
        "uid": "CR3bdJZkiaAuh9yr0OHXJJPG",
        "alias": "my-alias-2",
        "created": "2016-06-01T21:03:10.420Z",
        "rules": [
            {
                "pathname": "/",
                "dest": "my-app-fjvngszyiq.now.sh"
            },
            {
                "dest": "my-api-ibzcpajvlo.now.sh"
            }
        ]
      }
    ]
  }`}</Code>
</Example>

### Get a Single Alias

<Endpoint>
  GET /v2/now/aliases/:id
  <br />
  GET /v2/now/aliases/:name
</Endpoint>

Get the information for a specific alias by passing either the alias `id` or `name` in the URL.

#### Output

<OutputTable>
  <Row>
    <BoldCell>uid</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The unique identifier of the alias.</Cell>
  </Row>
  <Row>
    <BoldCell>alias</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>The name of the alias.</Cell>
  </Row>
  <Row>
    <BoldCell>deployment</BoldCell>
    <TypeCell>Map</TypeCell>
    <Cell>
      An object containing the <InlineCode>id</InlineCode> and{' '}
      <InlineCode>url</InlineCode> of the deployment.
    </Cell>
  </Row>
  <Row>
    <BoldCell>created</BoldCell>
    <TypeCell>Date</TypeCell>
    <Cell>The date when the alias was created.</Cell>
  </Row>
  <Row>
    <BoldCell>projectId</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The unique identifier of the project.</Cell>
  </Row>
  <Row>
    <BoldCell>deploymentId</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The unique identifier of the deployment.</Cell>
  </Row>
</OutputTable>

<Example>
  <span>Example request:</span>

<Request
  method="GET"
  url="https://api.zeit.co/v2/now/aliases/2WjyKQmM8ZnGcJsPWMrHRHrE"
  auth
/>

Example successful (**200**) response:

<Code lang="json">{`{
  "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
  "alias": "my-alias.now.sh",
  "deployment": {
    "id": "dpl_2MfpYzxMJiiPVRs7ZYqo8US9dynT",
    "url": "my-alias-repfs93ww.now.sh"
  },
  "created": "2019-07-17T17:33:35.374Z",
  "projectId": "QmPMW4P9rKjheg6k3MckC7yZjRwMB6FdE8SZBerRvHWnYs",
  "deploymentId": "dpl_2MfpYzxMJiiPVRs7ZYqo8US9dynT"
}`}</Code>
</Example>

### Remove an Alias

<Endpoint method="DELETE" url="/v2/now/aliases/:id" />

The API allows you to delete an alias by supplying the alias `:id` in the url.
You can obtain this id from the list of aliases.

#### Output

<OutputTable>
  <Row>
    <BoldCell>status</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>If the alias was successfully removed.</Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  method="DELETE"
  url="https://api.zeit.co/v2/now/aliases/2WjyKQmM8ZnGcJsPWMrHRHrE"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`
  }}
/>

Example successful (**200**) response:

<Code lang="json">{`{
    "status": "SUCCESS"
  }`}</Code>
</Example>

### List aliases by deployment

<Endpoint method="GET" url="/v2/now/deployments/:id/aliases" />

Retrieves all of the aliases for the deployment with the given `:id`.
The authenticating user must own this deployment.
The body will contain an entry for each alias.

#### Output

<OutputTable>
  <Row>
    <BoldCell>aliases</BoldCell>
    <TypeCell>List</TypeCell>
    <Cell>A list of the aliases asigned to the deployment.</Cell>
  </Row>
</OutputTable>

#### Alias

This is the format of each item in the `aliases` list.

<OutputTable>
  <Row>
    <BoldCell>uid</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The unique identifier of the alias.</Cell>
  </Row>
  <Row>
    <BoldCell>alias</BoldCell>
    <TypeCell>String</TypeCell>
    <Cell>
      The alias name, it could be a <InlineCode>.now.sh</InlineCode> subdomain
      or a custom domain.
    </Cell>
  </Row>
  <Row>
    <BoldCell>created</BoldCell>
    <TypeCell>Date</TypeCell>
    <Cell>The date when the alias was created.</Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  url="https://api.zeit.co/v2/now/deployments/7Npest0z1zW5QVFfNDBId4BW/aliases"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`
  }}
/>

Example successful (**200**) response:

<Code lang="json">{`{
    "aliases": [
      {
        "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
        "alias": "my-alias",
        "created": "2016-06-02T21:01:40.950Z",
      }
    ]
  }`}</Code>
</Example>

### Assign an alias to a deployment

<Endpoint method="POST" url="/v2/now/deployments/:id/aliases" />

Creates a new alias for the deployment with the given `:id`. The authenticated user must own this deployment.

The JSON body of the POST should contain an `alias` key with the desired alias (hostname or custom url).

If the desired alias was used before it will be removed from the old deployment and assigned to the new one.

#### Input

<InputTable>
  <Row>
    <BoldCell>alias</BoldCell>
    <TypeCell>String</TypeCell>
    <BooleanCell status={true} />
    <Cell>
      The alias we want to assign to the deployment defined in the URL.
    </Cell>
  </Row>
</InputTable>

#### Output

<OutputTable>
  <Row>
    <BoldCell>oldID</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>
      The unique identifier of the previously aliased deployment, only received
      when the alias was used before.
    </Cell>
  </Row>
  <Row>
    <BoldCell>ui</BoldCell>
    <TypeCell>ID</TypeCell>
    <Cell>The unique identifier of the alias.</Cell>
  </Row>
  <Row>
    <BoldCell>created</BoldCell>
    <TypeCell>Date</TypeCell>
    <Cell>The date when the alias was created.</Cell>
  </Row>
</OutputTable>

<Example>
  Example request:

<Request
  method="POST"
  url="https://api.zeit.co/v2/now/deployments/7Npest0z1zW5QVFfNDBId4BW/aliases"
  headers={{
    Authorization: `Bearer ${
      props.testingToken ? props.testingToken.token : '$TOKEN'
    }`,
    'Content-Type': 'application/json'
  }}
  body={{
    alias: 'my-alias.now.sh'
  }}
/>

Example successful (**200**) response for new alias:

<Code lang="json">{`{
    "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
    "created": "2016-06-02T21:01:40.950Z"
  }`}</Code>

Example successful (**200**) response for alias with existing deployment
(<InlineCode>oldId</InlineCode> is the id of the previous deployment):

<Code lang="json">{`{
    "oldId": "c9MrOWGzdJSfPxqyTDYhdEGN",
    "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
    "created": "2016-06-02T21:01:40.950Z"
  }`}</Code>
</Example>
